'\" t
.\"     Title: \fBmysqlrplshow\fR
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 01/14/2017
.\"    Manual: MySQL Utilities
.\"    Source: MySQL 1.6.4
.\"  Language: English
.\"
.TH "\FBMYSQLRPLSHOW\FR" "1" "01/14/2017" "MySQL 1\&.6\&.4" "MySQL Utilities"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
mysqlrplshow \- Show Slaves for Master Server
.SH "SYNOPSIS"
.HP \w'\fBmysqlrplshow\ [\fR\fB\fIoptions\fR\fR\fB]\fR\ 'u
\fBmysqlrplshow [\fR\fB\fIoptions\fR\fR\fB]\fR
.SH "DESCRIPTION"
.PP
This utility shows the replication slaves for a master\&. It prints a graph of the master and the slaves connected labeling each with the host name and port number\&.
.PP
You must specify the
\fB\-\-discover\-slaves\-login \fR
option to provide the user name and password to discover any slaves in the topology\&.
.PP
The discover slaves option
\fBrequires\fR
all slaves use the
\-\-report\-host
and
\-\-report\-port
server startup variables with the correct hostname and port\&. If these are missing or report the incorrect information, the slave may not be detected and thus not included in the operation of the utility\&. The discover slaves option ignores any slaves to which it cannot connect\&.
.PP
To explore the slaves for each client, use the
\fB\-\-recurse\fR
option\&. This causes the utility to connect to each slave found and attempt to determine whether it has any slaves\&. If slaves are found, the process continues until the slave is found in the list of servers serving as masters (a circular topology)\&. The graph displays the topology with successive indents\&. A notation is made for circular topologies\&.
.PP
If you use the
\fB\-\-recurse\fR
option, the utility attempts to connect to the slaves using the user name and password provided for the master\&. By default, if the connection attempt fails, the utility throws an error and stops\&. To change this behavior, use the
\fB\-\-prompt\fR
option, which permits the utility to prompt for the user name and password for each slave that fails to connect\&. You can also use the
\fB\-\-num\-retries=n\fR
option to reattempt a failed connection \*(Aqn\*(Aq times before the utility fails\&.
.PP
An example graph for a typical topology with relay slaves is shown here:
.sp
.if n \{\
.RS 4
.\}
.nf
# Replication Topology Graph::
localhost:3311 (MASTER)
   |
   +\-\-\- localhost:3310 \- (SLAVE)
   |
   +\-\-\- localhost:3312 \- (SLAVE + MASTER)
       |
       +\-\-\- localhost:3313 \- (SLAVE)
.fi
.if n \{\
.RE
.\}
.PP
MASTER,
SLAVE, and
SLAVE+MASTER
indicate that a server is a master only, slave only, and both slave and master, respectively\&.
.PP
A circular replication topology is shown like this, where
<\-\->
indicates circularity:
.sp
.if n \{\
.RS 4
.\}
.nf
# Replication Topology Graph
localhost:3311 (MASTER)
   |
   +\-\-\- localhost:3312 \- (SLAVE + MASTER)
       |
       +\-\-\- localhost:3313 \- (SLAVE + MASTER)
           |
           +\-\-\- localhost:3311 <\-\-> (SLAVE)
.fi
.if n \{\
.RE
.\}
.PP
To produce a column list in addition to the graph, specify the
\fB\-\-show\-list\fR
option\&. In this case, to specify how to display the list, use one of the following values with the
\fB\-\-format\fR
option:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBgrid\fR
(default)
.sp
Display output in grid or table format like that of the
\fBmysql\fR
client command\-line tool\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBcsv\fR
.sp
Display output in comma\-separated values format\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBtab\fR
.sp
Display output in tab\-separated format\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBvertical\fR
.sp
Display output in single\-column format like that of the
\eG
command for the
\fBmysql\fR
client command\-line tool\&.
.RE
.PP
The utility uses of the
\fBSHOW SLAVE HOSTS\fR
statement to determine which slaves the master has\&. If you want to use the
\fB\-\-recurse\fR
option, slaves
\fBmust\fR
have been started with the
\-\-report\-host
and
\-\-report\-port
options set to their actual host name and port number or the utility may not be able to connect to the slaves to determine their own slaves\&.
OPTIONS.PP
\fBmysqlrplshow\fR
accepts the following command\-line options:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-\-help
.sp
Display a help message and exit\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-\-license
.sp
Display license information and exit\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-\-discover\-slaves\-login=\fIslave\-login\fR
.sp
Supply the user and password in the form
\fIuser\fR[:\fIpasswd\fR] or
\fIlogin\-path\fR
for discovering slaves and relay slaves in the topology\&. For example, \-\-discover=joe:secret uses \*(Aqjoe\*(Aq as the user and \*(Aqsecret\*(Aq as the password for each discovered slave\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-\-format=\fIformat\fR, \-f\fIformat\fR
.sp
Specify the display format for column list output\&. Permitted format values are
\fBgrid\fR,
\fBcsv\fR,
\fBtab\fR, and
\fBvertical\fR\&. The default is
\fBgrid\fR\&. This option applies only if
\fB\-\-show\-list\fR
is given\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-\-master=\fIsource\fR
.sp
Connection information for the master server\&.
.sp
To connect to a server, it is necessary to specify connection parameters such as the user name, host name, password, and either a port or socket\&. MySQL Utilities provides a number of ways to supply this information\&. All of the methods require specifying your choice via a command\-line option such as \-\-server, \-\-master, \-\-slave, etc\&. The methods include the following in order of most secure to least secure\&.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Use login\-paths from your
\&.mylogin\&.cnf
file (encrypted, not visible)\&. Example :
\fIlogin\-path\fR[:\fIport\fR][:\fIsocket\fR]
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Use a configuration file (unencrypted, not visible) Note: available in release\-1\&.5\&.0\&. Example :
\fIconfiguration\-file\-path\fR[:\fIsection\fR]
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Specify the data on the command\-line (unencrypted, visible)\&. Example :
\fIuser\fR[:\fIpasswd\fR]@\fIhost\fR[:\fIport\fR][:\fIsocket\fR]
.RE
.sp
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-\-max\-depth=\fIN\fR
.sp
The maximum recursion depth\&. This option is valid only if
\fB\-\-recurse\fR
is given\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-\-num\-retries=\fInum_retries\fR, \-n\fInum_retries\fR
.sp
The number of retries permitted for failed slave login attempts\&. This option is valid only if
\fB\-\-prompt\fR
is given\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-\-prompt, \-p
.sp
Prompt for the slave user and password if different from the master user and password\&.
.sp
If you give this option, the utility sets
\fB\-\-num\-retries\fR
to 1 if that option is not set explicitly\&. This ensures at least one attempt to retry and prompt for the user name and password should a connection fail\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-\-quiet, \-q
.sp
Turn off all messages for quiet execution\&. This option does not suppress errors or warnings\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-\-recurse, \-r
.sp
Traverse the list of slaves to find additional master/slave connections\&. User this option to map a replication topology\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-\-show\-list, \-l
.sp
Display a column list of the topology\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-\-ssl\-ca
.sp
The path to a file that contains a list of trusted SSL CAs\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-\-ssl\-cert
.sp
The name of the SSL certificate file to use for establishing a secure connection\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-\-ssl\-key
.sp
The name of the SSL key file to use for establishing a secure connection\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-\-ssl
.sp
Specifies if the server connection requires use of SSL\&. If an encrypted connection cannot be established, the connection attempt fails\&. Default setting is 0 (SSL not required)\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-\-verbose, \-v
.sp
Specify how much information to display\&. If this option is used, the IO thread status of each slave is also displayed\&. Use this option multiple times to increase the amount of information\&. For example,
\fB\-v\fR
= verbose,
\fB\-vv\fR
= more verbose,
\fB\-vvv\fR
= debug\&. If you use \-vvv, the output contains the state of the IO and SQL threads for each slave\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-\-version
.sp
Display version information and exit\&.
.RE
NOTES.PP
The login user must have the
\fBREPLICATE SLAVE\fR
and
\fBREPLICATE CLIENT\fR
privileges to successfully execute this utility\&. Specifically, the login user must have appropriate permissions to execute
\fBSHOW SLAVE STATUS\fR,
\fBSHOW MASTER STATUS\fR, and
\fBSHOW SLAVE HOSTS\fR\&.
.PP
For the
\fB\-\-format\fR
option, the permitted values are not case sensitive\&. In addition, values may be specified as any unambiguous prefix of a valid value\&. For example,
\fB\-\-format=g\fR
specifies the grid format\&. An error occurs if a prefix matches more than one valid value\&.
.PP
Mixing IP and hostnames is not recommended\&. The replication\-specific utilities attempt to compare hostnames and IP addresses as aliases for checking slave connectivity to the master\&. However, if your installation does not support reverse name lookup, the comparison could fail\&. Without the ability to do a reverse name lookup, the replication utilities could report a false negative that the slave is (not) connected to the master\&.
.PP
For example, if you setup replication using MASTER_HOST=ubuntu\&.net on the slave and later connect to the slave with mysqlrplcheck and have the master specified as \-\-master=192\&.168\&.0\&.6 using the valid IP address for ubuntu\&.net, you must have the ability to do a reverse name lookup to compare the IP (192\&.168\&.0\&.6) and the hostname (ubuntu\&.net) to determine if they are the same machine\&.
.PP
The path to the MySQL client tools should be included in the PATH environment variable in order to use the authentication mechanism with login\-paths\&. This permits the utility to use the my_print_defaults tools which is required to read the login\-path values from the login configuration file (\&.mylogin\&.cnf)\&.
EXAMPLES.PP
To show the slaves for a master running on port 3311 on the local host, use the following command:
.sp
.if n \{\
.RS 4
.\}
.nf
shell> \fBmysqlrplshow  \-\-master=root@localhost:3311 \-\-discover\-slaves\-login=root\fR
# master on localhost: \&.\&.\&. connected\&.
# Finding slaves for master: localhost:3311
# Replication Topology Graph
localhost:3311 (MASTER)
   |
   +\-\-\- localhost:3310 \- (SLAVE)
   |
   +\-\-\- localhost:3312 \- (SLAVE)
.fi
.if n \{\
.RE
.\}
.PP
As shown in the example, you must provide valid login information for the master\&.
.PP
To show additional information about the IO thread status (to confirm if the slaves are really connected to the master) use the option
\fB\-\-verbose\fR:
.sp
.if n \{\
.RS 4
.\}
.nf
shell> \fBmysqlrplshow  \-\-master=root@localhost:3311 \-\-discover\-slaves\-login=root\fR \-\-verbose
# master on localhost: \&.\&.\&. connected\&.
# Finding slaves for master: localhost:3311
# Replication Topology Graph
localhost:3311 (MASTER)
   |
   +\-\-\- localhost:3310 [IO: Yes, SQL: Yes] \- (SLAVE)
   |
   +\-\-\- localhost:3312 [IO: Yes, SQL: Yes] \- (SLAVE)
.fi
.if n \{\
.RE
.\}
.PP
To show the full replication topology of a master running on the local host, use the following command:
.sp
.if n \{\
.RS 4
.\}
.nf
shell> \fBmysqlrplshow  \-\-master=root@localhost:3311 \-\-recurse \-\-discover\-slaves\-login=root\fR
# master on localhost: \&.\&.\&. connected\&.
# Finding slaves for master: localhost:3311
# Replication Topology Graph
localhost:3311 (MASTER)
   |
   +\-\-\- localhost:3310 \- (SLAVE)
   |
   +\-\-\- localhost:3312 \- (SLAVE + MASTER)
       |
       +\-\-\- localhost:3313 \- (SLAVE)
.fi
.if n \{\
.RE
.\}
.PP
To show the full replication topology of a master running on the local host, prompting for the user name and password for slaves that do not have the same user name and password credentials as the master, use the following command:
.sp
.if n \{\
.RS 4
.\}
.nf
shell> \fBmysqlrplshow \-\-recurse \-\-prompt \-\-num\-retries=1 \e\fR
          \fB\-\-master=root@localhost:3331 \-\-discover\-slaves\-login=root\fR
Server localhost:3331 is running on localhost\&.
# master on localhost: \&.\&.\&. connected\&.
# Finding slaves for master: localhost:3331
Server localhost:3332 is running on localhost\&.
# master on localhost: \&.\&.\&. FAILED\&.
Connection to localhost:3332 has failed\&.
Please enter the following information to connect to this server\&.
User name: root
Password:
# master on localhost: \&.\&.\&. connected\&.
# Finding slaves for master: localhost:3332
Server localhost:3333 is running on localhost\&.
# master on localhost: \&.\&.\&. FAILED\&.
Connection to localhost:3333 has failed\&.
Please enter the following information to connect to this server\&.
User name: root
Password:
# master on localhost: \&.\&.\&. connected\&.
# Finding slaves for master: localhost:3333
Server localhost:3334 is running on localhost\&.
# master on localhost: \&.\&.\&. FAILED\&.
Connection to localhost:3334 has failed\&.
Please enter the following information to connect to this server\&.
User name: root
Password:
# master on localhost: \&.\&.\&. connected\&.
# Finding slaves for master: localhost:3334
# Replication Topology Graph
localhost:3331 (MASTER)
   |
   +\-\-\- localhost:3332 \- (SLAVE)
   |
   +\-\-\- localhost:3333 \- (SLAVE + MASTER)
       |
       +\-\-\- localhost:3334 \- (SLAVE)
.fi
.if n \{\
.RE
.\}
.sp
PERMISSIONS REQUIRED.PP
The user connected to the master must have the REPLICATION SLAVE privilege\&.
.PP
The user specified with the
\fB\-\-discover\-slaves\-login\fR
option that logs into each slave must have the REPLICATION CLIENT privilege\&.
.SH "COPYRIGHT"
.br
.PP
Copyright \(co 2006, 2017, Oracle and/or its affiliates. All rights reserved.
.PP
This documentation is free software; you can redistribute it and/or modify it only under the terms of the GNU General Public License as published by the Free Software Foundation; version 2 of the License.
.PP
This documentation is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
.PP
You should have received a copy of the GNU General Public License along with the program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA or see http://www.gnu.org/licenses/.
.sp
.SH "SEE ALSO"
For more information, please refer to the MySQL Utilities and Fabric
documentation, which is available online at
http://dev.mysql.com/doc/index-utils-fabric.html
.SH AUTHOR
Oracle Corporation (http://dev.mysql.com/).
